<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="description" content="None">
  
  
  <link rel="shortcut icon" href="img/favicon.ico">
  <title>COROS Documentation</title>
  <link rel="stylesheet" href="css/theme.css" />
  <link rel="stylesheet" href="css/theme_extra.css" />
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" />
  
  <script>
    // Current page data
    var mkdocs_page_name = "Home";
    var mkdocs_page_input_path = "index.md";
    var mkdocs_page_url = null;
  </script>
  
  <script src="js/jquery-2.1.1.min.js" defer></script>
  <script src="js/modernizr-2.8.3.min.js" defer></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
  <script>hljs.initHighlightingOnLoad();</script> 
  
</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
    <div class="wy-side-scroll">
      <div class="wy-side-nav-search">
        <a href="." class="icon icon-home"> COROS Documentation</a>
        <div role="search">
  <form id ="rtd-search-form" class="wy-form" action="./search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" title="Type search term here" />
  </form>
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
                <ul class="current">
                    <li class="toctree-l1 current"><a class="reference internal current" href=".">Home</a>
    <ul class="current">
    <li class="toctree-l2"><a class="reference internal" href="#description">Description</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#software-architecture">Software architecture</a>
        <ul>
    <li class="toctree-l3"><a class="reference internal" href="#coroutines">Coroutines</a>
        <ul>
    <li class="toctree-l4"><a class="reference internal" href="#coroutines-vs-pre-emptive-tasking">Coroutines vs. pre-emptive tasking</a>
    </li>
    <li class="toctree-l4"><a class="reference internal" href="#coroutines-vs-asynchronous-reactors">Coroutines vs. asynchronous reactors</a>
    </li>
        </ul>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#event-queues">Event queues</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#components">Components</a>
    </li>
        </ul>
    </li>
    </ul>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">About</span></p>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="COPYRIGHT/">Copyright</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="LICENSE/">License</a>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">The Beginner's Guide to:</span></p>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="tutorials/01_getting_started/">Getting Started</a>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">The Hitchker's Guide to:</span></p>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="guides/01_coroutines/">Coroutines</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="guides/02_event_queues/">Event Queues</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="guides/03_components/">Components</a>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">The Technocrat's Guide to:</span></p>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="reference/01_co/">co.h</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="reference/02_evq/">evq.h</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="reference/03_comp/">comp.h</a>
                    </li>
                </ul>
                <p class="caption"><span class="caption-text">The Technomancer's Guide to:</span></p>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="architecture/01_coroutines/">Coroutines</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="architecture/02_event_queues/">Event Queues</a>
                    </li>
                    <li class="toctree-l1"><a class="reference internal" href="architecture/03_porting/">Porting</a>
                    </li>
                </ul>
      </div>
    </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href=".">COROS Documentation</a>
      </nav>

      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href=".">Docs</a> &raquo;</li>
    
      
    
    <li>Home</li>
    <li class="wy-breadcrumbs-aside">
      
    </li>
  </ul>
  
  <hr/>
</div>
          <div role="main">
            <div class="section">
              
                <h1 id="coros-documentation">COROS Documentation</h1>
<h2 id="description">Description</h2>
<p>COROS is a CORoutine-based real-time OS kernel written in C and suited to a wide variety of embedded software systems where the complexity and non-determinism of pre-emptive scheduling is not desired.</p>
<h2 id="software-architecture">Software architecture</h2>
<p>The key architectural features COROS brings to the table are:</p>
<ol>
<li>Coroutines for concurrency.</li>
<li>A segmented event queue for inter-task (or, rather, more usefully, inter-component) communication.</li>
<li>A component wrapper that provides Kay-style OOP (independent software entities communicating through messages) in an efficient, simple wrapper.</li>
</ol>
<h3 id="coroutines">Coroutines</h3>
<p>Coroutines are essentially generalizations of procedures and functions (procedures).  A proper procedure has a single entry point and a single exit point.  A common optimization of procedures is to allow more than one exit point, but you still always enter at the top.</p>
<p>A coroutine is a procedure that can have multiple exit points <em>and</em> multiple entry points.  A coroutine can exit in the middle, and when resumed will carry on from where it exited, not from the top.</p>
<h4 id="coroutines-vs-pre-emptive-tasking">Coroutines vs. pre-emptive tasking</h4>
<p>Coroutines are self-synchronizing and thus do not need to worry about critical sections or mutexes or the like.  They are also far higher-performing than a pre-emptive context switch.  The lack of arbitrary interruption points also leads to code that is far easier to reason about.</p>
<p>On the other hand, coroutines are not as flexible as pre-emptive tasking.  You have to be very attentive to how much time you're consuming and will have to manually give up time for other processing instead of having the system do it for you.  Also, priorities are manually managed in COROS, though some tools are provided in the event queue system to help support this.</p>
<h4 id="coroutines-vs-asynchronous-reactors">Coroutines vs. asynchronous reactors</h4>
<p>Common asynchronous concurrency systems use systems of callbacks.  (This is especially prevalent in the web world or projects in other realms that are written by web-influenced developers.)  There is a particular problem with these that has its own terminology: callback Hell.  Nested callbacks are non-trivial to write, non-trivial to reason about and tend to read like they're inside-out and backwards.</p>
<p>Coroutines permit the same sort of concurrency that asychronous reactors do, but they do so with code that is linear and easy to read.  When a coroutine yields, it pauses execution like returning from a callback, but when called back they continue from the point they yielded.  This leads to code that is written outside-in and forwards.</p>
<h3 id="event-queues">Event queues</h3>
<p>COROS is an event-driven system at its core.  It essentially wraps the typical embedded system ...</p>
<pre><code class="language-C">while(true) {
    if (condition1) { action1(); }
    if (condition2) { action2(); }
    if (condition3) { action3(); }
    if (condition4) { action4(); }
    /* ... and so on ... */
}
</code></pre>
<p>... architecture into a better-regulated, better-segregated, more-consistent event queue.  The event queue is segmented for ease of enabling and disabling features on the fly, as well as for simulating priority.  Events can be simple function callbacks for quick and easy features, or they can be a full-on coroutine context switch.  Events can be processed in a permanent loop, for time-bounded durations, or for one single "tick" and, importantly, these processing loops can be nested.  When the event queue is idle it can run background tasks (like a watchdog feeder, say).</p>
<h3 id="components">Components</h3>
<p>Components attach a disciplined approach to using coroutines and event queues in an embedded environment.  Notionally at their core, each component is a paired coroutine and an event queue.  Each component's event queue is attached to a parent component or system root event queue providing a degree of priority and localization of events and event processing.  These component members, however, are shielded from outside view and only API functions, often wrappers around messages sent via the event queue.  This permits decoupling of components from their clients and allows patterns like proxies, anonymous interfaces and the like to be used in assembling systems from components as well as easier porting of useful components to other hardware.</p>
              
            </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="COPYRIGHT/" class="btn btn-neutral float-right" title="Copyright">Next <span class="icon icon-circle-arrow-right"></span></a>
      
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
    
  </div>

  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
      
        </div>
      </div>

    </section>

  </div>

  <div class="rst-versions" role="note" aria-label="versions">
    <span class="rst-current-version" data-toggle="rst-current-version">
      
      
      
        <span style="margin-left: 15px"><a href="COPYRIGHT/" style="color: #fcfcfc">Next &raquo;</a></span>
      
    </span>
</div>
    <script>var base_url = '.';</script>
    <script src="js/theme.js" defer></script>
      <script src="search/main.js" defer></script>
    <script defer>
        window.onload = function () {
            SphinxRtdTheme.Navigation.enable(true);
        };
    </script>

</body>
</html>

<!--
MkDocs version : 1.1.2
Build Date UTC : 2025-10-27 02:41:08.916142+00:00
-->
